COS computes cosine ARITHMETIC 
Synopsis: cos: proc (floating) returns (floating); 
Usage: result = cos (num); 
COS returns the cosine of NUM, where NUM is the angle in 
radians. 
Example: 
del (x, y) floating; 
x = cos (y); 
See also: SIN 
TAN 
ATN 
EXIT terminates program execution PROGRAM TERMINATION 
Synopsis: exit: proce (fixed); 
Usage: call exit (status); 
where STATUS is the program termination status returned 
to the Monitor. STATUS should be a zero if the program 
completed successfully or -1 if the program aborted. 
Control is returned to the Monitor following the EXIT 
statement. 
Example: 
when break then call exit (0); /* terminate on BREAK #/ 
if find device (dev) = 0 then do; /* DEV not configured */ 
print 'Device is not configured in system'; 
call exit (-1); /* abort program */ 
end; 
See also: STOP 
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EXP 


Synopsis: 


Usage: 


Example: 


See also: 


EXPORT 


Synopsis: 


Usage: 


Example: 


See also: 


computes natural anti-logarithm ARITHMETIC 


exp: proc (floating) returns (floating); 
result = exp (num); 


EXP returns the natural anti-logarithm of NUM. This is 
equal to e (e = 2.71828...) raised to the power of NUM. 


XPL does not provide functions for raising 10 to the 
power of X or Y to the power of X, but these functions 
ean be derived from EXP as follows: 
ten'to the x (x) = exp (log (10)*x) 
x_to the y (x, y) = exp (log (x)#y) 
del (x, y) floating; 
y = exp (x)#10; 


LOG 
SQR 


copies an array into external memory BLOCK MANIPULATION 


export: proce (fixed, fixed, fixed array, fixed); 

eall export (sector, word, buffer, length); 

This routine copies the first LENGTH words from BUFFER 
into external memory starting at the address specified by 
SECTOR and WORD (WORD is not restricted to 256). 


The LOCATION and ADDR functions can be used to create 
pointers to specific array or memory locations. 


call export (0, 0, buf, 256); 
call export (sector, wd, loc (addr (buf (ptr))), len); 


EXTSET 
IMPORT 
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EXTREAD reads data into external memory STORAGE I/0 


Synopsis: extread: proc (fixed, fixed, fixed array); 
Usage: call extread (ms sector, ls sector, ext data); 


where MS SECTOR and LS SECTOR form a 32-bit word pair 
that identifies the device and sector number that is to 
be read. The upper eight bits (byte) of this word pair 
specify the storage device number and the lower 24-bits 
specify the sector number on that device. EXT DATA is a 
fixed array which contains the following information: 


ext data (0) 
ext data (1) 
ext data (2) 
ext data (3) 


base sector in external memory 
word offset from base sector 
number of sectors to read 

number of words beyond last sector 
to read 


Data will be read from a storage device at MS SECTOR and 
LS SECTOR into external memory. The location in external 
memory to write to and the amount of data to transfer are 
both specified in the array EXT DATA. Neither the word 
offset nor the word length are restricted to 256. 


NOTE: If the device you are using with EXTREAD is a SCSI 
device, you must insert :-XPL:SCSISWAP into your program. 


Example: 
del info (3) fixed; /* array for using EXTREAD #/ 


info (0) = 104; /® sector 104 of external memory */ 
info (1) = 0; /* no word offset */ 
info (2) = 0; /* no sectors */ 
info (3) = file len; /* read entire file */ 
/* read file from disk into external memory */ 
call extread (ms file start, 1s file start, info); 
See also: EXTWRITE 


READDATA 
WRITEDATA 
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EXTSET initialize a block of external memory BLOCK MANIPULATION 


Synopsis: extset: proc (fixed, fixed, fixed, fixed); 

Usage: call extset (sector, word, length, value); 
This routine assigns VALUE to LENGTH words of external 
memory starting at the address specified by SECTOR and 
WORD. WORD is not restricted to 256. 

Example: 


call extset (0, 0, 256, 0); 
call extset (sector, word, len, i); 


See also: EXPORT 
IMPORT 
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EXTWRITE writes data from external memory STORAGE I/0 


Synopsis:  extwrite: proc (fixed, fixed, fixed array); 
Usage: call extwrite (ms sector, ls sector, ext: data); 


where MS SECTOR and LS SECTOR form a 32-bit word pair 
that identifies the device and sector number where data 
is to be written. The upper eight bits (byte) of this 
word pair specify the storage device number and the lower 
24-bits specify the sector number on that device. 

EXT DATA is a fixed array which contains the following 
information: 


ext data (0) 
ext data (1) 
ext data (2) 
ext™data (3) 


base sector in external memory 
word offset from base sector 
number of sectors to write 

number of words beyond last sector 
to write 


Data will be written from external memory to a storage 
device at MS SECTOR and LS:SECTOR. The location in 
external memory to read from and the amount of data to 
transfer are both specified in the array EXT: DATA. 
Neither the word offset nor the word length Ts restricted 
to 256. 


NOTE: If the device you are using with EXTWRITE is a 
SCSI device, you must insert :-XPL:SCSISWAP into your 
program. 


Example: 
del info (3) fixed; /* array for using EXTWRITE #/ 


info (0) = ptr; /® sector number in external memory */ 
info (1) = words; /*® word offset */ 

info (2) = 24; /* read 24 sectors */ 

info (3) = 0; /* no extra word length #/ 


/* write data from external memory to disk location */ 


call extwrite (f#ms sector, f#ls sector, info); 


See also: EXTREAD 
READDATA 
WRITEDATA 
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FIND’ DEVICE finds the configuration of a device SYSTEM 


Synopsis: find device: proc (fixed) returns (pointer); 
Usage: ptr = find device (dev_num); 


where DEV NUM is a valid system device number. If a 
valid device number is passed, and that device is 
configured in the system, FIND DEVICE returns an absolute 
memory pointer to the storage device table entry for that 
device. Otherwise, it returns a null pointer. 


Example: 
p = find device (7); /* look for the W1 Winchester */ 
if p <> null then do; /*® the device was found */ 
end; 
else print 'W1 Winchester disk is not configured.'; 
IMPORT copies from ext memory into an array BLOCK MANIPULATION 


Synopsis: import: proce (fixed, fixed, fixed array, fixed); 
Usage: call import (sector, word, buffer, length); 
This routine copies LENGTH words into BUFFER from 
external memory starting at the address specified by 
SECTOR and WORD. WORD is not restricted to 256. 


The LOCATION and ADDR functions can be used to create 
pointers to specifie array or memory locations. 


Examples: call import (0, 0, buf, 256); 
call import (sector, 0, loe (addr (buf (ptr))), len); 


See also: EXPORT 
EXTSET 
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INT . eonverts floating point to fixed point ARITHMETIC 


Synopsis: int: proe (floating) returns (fixed); 
Usage: result = int (num); 


The INT function converts the floating point parameter 
NUM into a fixed point number, which is returned. NUM is 
rounded towards negative infinity. That is, positive 
numbers are truncated (the fractional part is dropped), 
while negative numbers are set to the nearest more 
negative integer (int (-1.1) = -2). 


Example: 
del (x, y) floating; 
del i fixed; 


i = int (x + y); /* store integer sum in variable I #/ 


BUILT-IN FUNCTIONS 117 SCIENTIFIC XPL 


LOCATION references memory locations in procedure calls POINTERS 


Synopsis: location: proce (pointer) returns (fixed array); 
location: proe (pointer) returns (floating array); 


Usage: call proc name (location (expression)); 


The LOCATION function is used to reference absolute 
locations of memory during a procedure call. LOCATION 
ean only appear in an actual parameter list during a 
procedure call. The absolute memory location is passed 
to the procedure as the start of an array (either fixed 
or floating point). LOCATION can be shortened to LOC. 


LOCATION is often used in conjunction with the ADDR 
function in order to read from or write to an array 
starting at an element other than element zero. 


If a program tries to read a location of memory that does 
not exist, the computer will halt and the program will 
stop running. 
Example: 
/* Read a sector from disk into memory starting at 
location 8192. */ 
call readdata (ms_sec, 1s sec, loc (8192), 256); 
/* This example fills a string with nulls starting 
at word one of the string, leaving word zero 
(the string length) intact. */ 
eall blockset (loc (addr (string (1))), str_len, 0); 


See also: ADDR 
CORE 
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LOG 


Synopsis: 


Usage: 


Example: 


See also: 


computes natural logarithm ARITHMETIC 


log: proe (floating) returns (floating); 
result = log (num); 


LOG returns the natural logarithm (i.e., log base e) of 
NUM. NUM must be a positive non-zero number. 


XPL does not provide functions for log base 10 or log 
base X, but these functions can be derived from LOG as 
follows: 


log 10 (x) 
log x (x, y) 


log (x)/log (10) 
log (y)/log (x) 


del (x, y) floating; 


x = log (y); 


EXP 
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PBYTE writes a byte into a string STRING FUNCTIONS 


Synopsis: pbyte: proc (fixed array, fixed, fixed); 
Usage: call pbyte (string, byte num, value); 


where STRING is an XPL string, BYTE NUM is the byte 
‘position in the array (starting from zero), and VALUE is 
the number to store there. The lower 8 bits of VALUE 
will be written to the byte location specified by 

BYTE NUM. Only the appropriate upper or lower byte of 
the array element is altered. 


PBYTE is usually used with fixed arrays that are XPL 
strings, as each character is represented by one byte 
(two characters per word). When using PBYTE, the first 
byte (byte position 0) corresponds to the lower half of 
word one of the array. This leaves the string length in 
the first word (element 0) of the array. 


PBYTE can be used with fixed arrays that are not strings, 
to manipulate data elements by byte rather than by word. 
In this case the LOCATION and ADDR functions must be used 


to access the first word (element 0) of the array, as 
shown below: 


del list (100) fixed array; 
call pbyte (loe (addr (list (0)) - 1), byte num, i); 
Example: 
del line (8) fixed array; /* string of 16 characters */ 
del i fixed; 
do i = 0 to 15; 
call pbyte (line, i, a.x); /* fill line with X's #/ 
end; 


call pbyte (line, 9, a.sp); /* put a space in the middle */ 


see also: BYTE 
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POLYREAD reads data into polyphonic memory STORAGE I/0 


Synopsis: polyread: proc (fixed, fixed, fixed array, fixed); 
Usage: call polyread (ms_sector, ls_ sector, poly data, channel); 


where MS SECTOR and LS SECTOR form a 32-bit word pair 
that identifies the device and sector number that is to 
be read. The upper eight bits (byte) of this word pair 
specify the storage device number and the lower 24-bits 
specify the sector number on that device. POLY DATA is a 
fixed array which contains the following information: 


poly data (0) 
poly data (1) 
poly data (2) 
poly data (3) 


base sector in polyphonic memory 
word offset from base sector 
number of sectors to read 

number of words beyond last sector 
to read 


Data will be read from a storage device at MS SECTOR and 
LS SECTOR into polyphonic sampling memory. The location 
in polyphonic memory to write to and the amount of data 
to transfer are. both specified in the array POLY DATA. 
Neither the word offset nor the word length is restricted 
to zero. The data will be transferred through the 
indicated polyphonic CHANNEL (0-31). CHANNEL is usually 
zero; an interrupt handler could pass the channel being 
used at the time of interrupt (read ("155")). 


NOTE: If the device you are using with POLYREAD is a 
SCSI device, you must insert :-XPL:SCSISWAP into your 
program. 


Example: 
del info (3) fixed; /* array for using POLYREAD */ 


info (0) = 10; /* sector 10 of poly memory #*/ 

info (1) = 0; /* no word offset */ 

info (2) = 0; /* no sectors *#/ 

info (3) = file len; /* read the whole file */ 

/* read file from disk into polyphonic memory */ 

call polyread (ms file start, ls file start, info, 0); 
See also: POLYWRITE 


READDATA 
WRITEDATA 
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POLYWRITE 


Synopsis: 


Usage: 


Example: 


See also: 


writes data from polyphonic memory STORAGE I/0 


polywrite: proc (fixed, fixed, fixed array, fixed); 
call polywrite (ms ‘sector, ls sector, poly data, channel); 


where MS SECTOR and LS SECTOR form a 32-bit word pair 
that identifies the device and sector number where data 
is to be written. The upper eight bits (byte) of this 
word pair specify the storage device number and the lower 
24-bits specify the sector number on that device. 

POLY DATA is a fixed array which contains the following 
information: 


poly data (0) 
poly data (1) 
poly data (2) 
poly data (3) 


base sector in polyphonic memory 
word offset from base sector 
number of sectors to write 

number of words beyond last sector 
to write 


Data will be written from polyphonic sampling memory to a 
storage device at MS SECTOR and LS SECTOR. The location 
in polyphonic memory to read from and the amount of data 
to transfer are both specified in the array POLY DATA. 
Neither the word offset nor the word length is restricted 
to 256. The data transfer will occur through the 
indicated polyphonic CHANNEL (0-31). CHANNEL is usually 
zero; an interrupt handler could pass the channel being 
used at the time of interrupt (read ("155")). 


NOTE: If the device you are using with POLYWRITE is a 


SCSI device, you must insert :-XPL:SCSISWAP into your 
program. 


del info (3) fixed; /* array for using POLYWRITE #*/ 


info (0) = ptr; /*® sector number in polyphonic memory */ 
info (1) = words; /* word offset */ 

info (2) = 12; /* read 12 sectors */ 

info (3) = 0; /* no extra word length #/ 


/* write data from polyphonic memory to disk location */ 
call polywrite (f#ms_ sector, f#ls sector, info, 0); 
POLYREAD 


READDATA 
WRITEDATA 
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RCVDCHARACTER gets last character from terminal interrupt SYSTEMS 


Synopsis: revdeharacter: proc returns (fixed); 
Usage: eh = revdcharacter; 
RCVDCHARACTER returns the last character that was 


received from a terminal interrupt. It is normally used 
in a WHEN TTIINT statement (the terminal input 


interrupt). 
Example: 
when ttiint then begin; 
del ch fixed; /* character typed bu user */ 
ch = revdeharacter; /* get the character */ 
print "You just typed: ', char (ch); 
end; 


READ reads a word from an interface device HARDWARE 


Synopsis: read: proce (fixed) returns (fixed); 

Usage: i = read (device number); 
The READ function reads a value from the interface module 
specified by DEVICE NUMBER and returns that value to the 
program. DEVICE NUMBER can be a constant expression or a 
variable expression, although the READ will be much 
slower in the latter case. 


If an attempt is made to read a device that is not in the 
system, the computer will halt. 


Example: 
del timer literally '"03"'; 
del i fixed; 


i = read (timer); 


See also: WRITE 
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READDATA reads data from a storage device STORAGE I/0 


Synopsis: readdata: proc (fixed, fixed, fixed array, fixed); 
Usage: call readdata (mssector, 1s sector, buffer, length); 


where MS SECTOR and LS SECTOR form a 32-bit word pair 
that identifies the device and sector number that is to 
be read. The upper eight bits (byte) of this word pair 
specify the storage device number and the lower 24-bits 
specify the sector number on that device. LENGTH words 
of data will be read into BUFFER from this device and 
sector location. 


When using READDATA to access Winchester systems with 
more than one drive attached to a device, XPL will 
automatically determine which physical Winchester disk 
contains the specified logical sector. 


NOTE: If the device you are using with READDATA is a 
SCSI device, you must insert either :-XPL:SCSI or 
:-XPL:SCSISWAP into your program. 

Example: 
del buf (256) fixed; 
call readdata (shl (2, 8), 84, buf, 256); 
In this example, one sector (256 words) of the floppy 
disk in the FO drive is read. The number 2 is in the 


upper byte (device specifier for FO), and the sector 
address is 84, 


See also: WRITEDATA 


BUILT-IN FUNCTIONS 124 SCIENTIFIC XPL 


ROT rotates a word to the left BIT MANIPULATION 


Synopsis: rot: proc (fixed, fixed) returns (fixed); 
Usage: result = rot (number, bit count); 


ROT returns a value that is equal to NUMBER rotated left 
BIT COUNT bit positions. BIT COUNT must be in the range 
0-15. Each bit of VALUE will be shifted to the left 

BIT COUNT positions, with the most significant bit 
rotating into the least significant position. Notice the 
following example, where the number 5000 is rotated 4 


positions: 
i = 5000; /* i = 0001001110001000 #*/ 
js rot (i, 4); /* j = 0011100010000001 #/ 


Example: 
del (i, j) fixed; 


i = rot (j, 8); /*® swap the upper and lower bytes */ 


See also: SHL 
SHR 
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SET CURDEV sets the current device SYSTEM 


Synopsis: set_curdev: proc (fixed) returns (boolean); 
Usage: if set: curdev (dev num) then ... 


where DEV NUM is a valid system device number. 

SET’ CURDEV sets the current device to be the passed 
device number. If the operation is successful, a TRUE is 
returned. If an invalid device number is passed, or if 
the device is not configured in the system, a FALSE is 
returned and the current device is not changed. 


Example: 


if not set _curdev (dev_num) /* could not change device */ 
then do; 

print '##* System Error!'; 

print 'Could not change current device to ', dev_num; 
end; 
else do; /* current device was set to DEV_NUM */ 


end; 
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SHL shifts a word to the left BIT MANIPULATION 


Synopsis: shl: proce (fixed, fixed) returns (fixed); 
Usage: result = shl (number, bit count); 


SHL returns a value that is equal to NUMBER shifted to 
the left BIT COUNT bit positions. BIT COUNT must be in 
the range 0-15. Bits shifted off the Teft end will be 
lost, and bits shifted into the right end will be zeros. 
Notice the following example, where the number 5000 is 
shifted left 4 positions: 


5000; y* 


i< i = 0001001110001000 #/ 
j= shl (i, 4); /* j 


0011100010000000 #/ 


Example: 
del dev fixed; /* device number */ 
del ms sector fixed; /* MS word of starting sector #®/ 
del ls sector fixed; /* LS word of starting sector */ 
del sec fixed; /* number of sectors to read */ 
del buf (2048) fixed; /* data buffer */ 


/* The following code sets up a word pair that has a 
device number in the upper byte and the starting 
sector of a file in the lower 24 bits. This is the 
standard way of specifying a file location. */ 

dev = shl (dev, 8); /® put device in the upper byte */ 


/* Use AND to make sure that MS SECTOR has only the 
bottom 8 bits, then OR the device into it. */ 


ms_ sector = (dev or (ms sector and "377")); 

/* Now read the first SEC sectors of the file. 
Notice the word length is given by multiplying the 
sector length by 256, or SHL by 8. */ 

call readdata (ms_sector, 1s sector, buf, shl (sec, 8)); 


See also: SHR 
ROT 


BUILT-IN FUNCTIONS 127 SCIENTIFIC XPL 


SHR shifts a word to the right BIT MANIPULATION 


Synopsis: shr: proc (fixed, fixed) returns (fixed); 
Usage: result = shr (number, bit count); 


SHR returns a value that is equal to NUMBER shifted to 
the right BIT COUNT bit positions. BIT COUNT must be in 
the range 0-15, Bits shifted off the right end will be 
lost, and bits shifted into the left end will be zeros. 
Notice the following example, where the number 5000 is 
shifted right 4 positions: 


i 
N 


5000; /*® i 
shr (i, 4); /* j 


0001001110001000 #/ 
0000000100111000 #/ 


Won 


Example: 
del device fixed; /* device number */ 
del words fixed; /*® number of words */ 
del sectors fixed; /* number of sectors */ 


/* extract the device from the upper byte of word pair 
identifying file location */ 


device = shr (f#ms sector, 8); 
/* sectors is words divided by 256, or SHR of 8 */ 


sectors = shr (words, 8); 


See also: SHL 
ROT 
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SIN computes sine ARITHMETIC 


Synopsis: sin: proce (floating) returns (floating); 
Usage: result = sin (num); 


SIN returns the sine of NUM, where NUM is the angle in 
radians. 


Example: 
del (x, y) floating; 


x = sin (y)#y; 
See also: COS 


TAN 
ATN 


SQR computes square root ARITHMETIC 


Synopsis: sqr: proc (floating) returns (floating); 
Usage: result = sqr (num); 


SQR returns the square root of NUM, where NUM must be a 
positive number. 


XPL does not provide functions for cube roots or the Xth 
root of Y, but these functions can be derived from LOG 
and EXP as follows: 


cube root (x) = exp (log (x)/3.0) 
xth root of y (x, y) = exp (log (y)/x) 


Example: 
del (x, y) fixed; 


print sar (x); 
y = sar (abs (x)); 


See also: ABS 
LOG 
EXP 
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STOP halts the computer PROGRAM TERMINATION 


Usage: stop; 
stop (value); 


The STOP statement is used to halt the computer at a 
predetermined point in a program. If STOP is used with a 
fixed point parameter, that VALUE will be written to the 
Hand Operated Processor (HOP) upon execution of the STOP 
statement. Pressing the SYNC button on the HOP will 
eause the program to continue from that point, or control 
ean be returned to the Monitor by pressing the Load 
button. The STOP statement is most often used for 
debugging purposes. 


Example: 
del status fixed; 


status = test device; /* eall testing procedure */ 
if status <> 0 then do; 


stop ("10"); /# write a value to HOP to mark this #*/ 
end; 


See also: EXIT 
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